Sphinx docs to GitHub Pages · Actions · GitHub Marketplace · GitHub |
您所在的位置：网站首页 › easier documentation with github pages infoworld › Sphinx docs to GitHub Pages · Actions · GitHub Marketplace · GitHub |
Sphinx docs to GitHub Pages · Actions · GitHub Marketplace · GitHub
|
action-sphinx-docs-to-gh-pages
The Sphinx documentation in a repository is automatically compiled as 'html' and deployed, by means of the gh-pages branch, with this GitHub Actions to GitHub Pages. The user has only to be sure that the repository accomplishes a couple of requirements. In summary, this GitHub action does the following: Takes the author and SHA id of the trigger action (push or pull request) to be consistent along the action. Creates a new gh-pages branch if this is not already in the repository. Compiles the sphinx documentation in the directory and branch specified by the user. Pushes the output html documentation to the gh-pages branch.This GitHub Action was developed by the Computational Biology and Drug Design Research Unit -UIBCDF- at the Mexico City Children's Hospital Federico Gómez (see also Contributers). Other GitHub Actions can be found at the UIBCDF GitHub site. Requirements GitHub Pages taking the source from the branch gh-pagesThere is no need to have a gh-pages branch already in the repository. This action will create it for you. But once this GitHub action runned for first time, make sure that GitHub Pages is taking the web source code from the branch gh-pages. In the github repository go to 'Settings -> Pages -> Source' and check that no other branch is selected as source. A YAML file to create a conda environment with docs compilation dependenciesThe compilation of your sphinx documentation requires dependencies that can be solved with a temporary conda environment. Make sure that the repository has a Yaml file with the details to make this environment (see the section "Documentation conda environment"). How to use itTo include this GitHub Action, create a YAML file (named sphinx_docs_to_gh_pages.yaml, for instance) with the following content in the directory .github/workflows of your repository: name: Sphinx docs to gh-pages on: push: branches: - main # workflow_dispatch: # Un comment line if you also want to trigger action manually jobs: sphinx_docs_to_gh-pages: runs-on: ubuntu-latest name: Sphinx docs to gh-pages steps: - uses: actions/checkout@v2 with: fetch-depth: 0 - name: Make conda environment uses: conda-incubator/setup-miniconda@v2 with: python-version: 3.7 # Python version to build the html sphinx documentation environment-file: devtools/conda-envs/docs_env.yaml # Path to the documentation conda environment auto-update-conda: false auto-activate-base: false show-channel-urls: true - name: Installing the library shell: bash -l {0} run: | python setup.py install - name: Running the Sphinx to gh-pages Action uses: uibcdf/[email protected] with: branch: main dir_docs: docs sphinxapiopts: '--separate -o . ../' sphinxapiexclude: '../*setup* ../*.ipynb' sphinxopts: ''Two things need to be known to run the GitHub Actions without further work: the meaning of the input parameters and the YAML file to make a temporary Conda environment where the sphinx documentation can be compiled. Input parametersThese are the input parameters of the action: Input parameters Description Default value branch Name of the branch where the sphinx documentation is located main dir\_docs Path where the sphinx documentation is located docs sphinxopts Compilation options for sphinx-build '-o . ../' spinxapiopts Options passed to sphinx-apidoc, typically the output directory and location to look for modules. '' sphinxapiexclude Files to be excluded from API documentation generation, by default tests/ are excluded. *setup* tests*They are placed in the last lines of the above workflow example file: - name: Running the Sphinx to gh-pages Action uses: uibcdf/[email protected] with: branch: main dir_docs: docs sphinxopts: '' sphinxapiopts: '--separate -o . ../' sphinxapiexclude: '../*.ipynb'In case your sphinx documentation is placed in a directory named 'docs' in the 'main' branch to be compiled with no further options, you can do without the section with:. Documentation RequirementsThe Sphinx documentation will need specific libraries and packages to be compiled. There are a few options to achieving this, one is to create a Conda environment in which to build the documentation. Alternatively if your package includes the [options.extras_require] docs section you can install these. Conda environmentThey can be specified in a Conda environment file. This way, a temporary enviroment can be made and activated to compile the documentation with all dependencies satisfied. Write a file in the repository with the following content: name: docs channels: - conda-forge - defaults dependencies: # Write here all dependencies to compile the sphinx documentation. # This list is just an example - python=3.7 - sphinx - sphinx_rtd_theme - sphinxcontrib-bibtex - nbsphinx - recommonmark - sphinx-markdown-tablesAnd replace the value of the workflow input parameter environment-file: with the right path to your documentation conda enviroment file. In the case of the above example ('devtools/conda-envs/docs_env.yaml'): jobs: sphinx_docs_to_gh-pages: steps: - name: Make conda environment uses: conda-incubator/setup-miniconda@v2 with: # Replace with the path to your documentation conda enviroment file environment-file: devtools/conda-envs/docs_env.yaml setup.cfgMany Python packages use setuptools for configuring installation via the setup.cfg file. One section of this is the [options.extras_require] where packages not required for running the package but used in testing or building documentation can be listed. To list your documentation build requirements add the following to your setup.cfg [options.extras_require] docs = sphinx |
【本文地址】